• chore(claude): add pkg-pr-new preview deploy lookup instructions #4767
• refactor(pegboard-gateway2): consolidate hibernation in-flight and tunnel flush #4754
• chore(kitchen-sink): configurable endpoint #4766
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765 👈 (View in Graphite)
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

Code Review

Overview

This PR does two things: renames StopReason → ShutdownKind across rivetkit-core, and eliminates all _ => fallthrough arms on enums (codifying the rule in CLAUDE.md). It's clean, well-scoped, and contains one embedded behavioral fix worth calling out explicitly.

Embedded Bug Fix (Behavioral Change)

The most important change is in map_envoy_stop_reason() in registry/mod.rs:

Old behavior:

let task_stop_reason = match reason {
    protocol::StopActorReason::SleepIntent => StopReason::Sleep,
    _ => StopReason::Destroy,  // GoingAway and Lost were treated as Destroy!
};

New behavior:

protocol::StopActorReason::GoingAway => ShutdownKind::Sleep,  // reallocation
protocol::StopActorReason::Lost      => ShutdownKind::Sleep,  // resurrection

This is correct: GoingAway (runner drain) and Lost (connection drop) are ephemeral restarts where the actor resurfaces with the same identity, so they should run onSleep semantics and preserve durable state — not fire onDestroy and wipe it. The old _ => fallthrough was silently causing permanent destroy semantics for what are actually transient evictions. Worth highlighting explicitly in the PR description since it's a behavioral change wrapped inside a refactor.

Code Quality

Positives:

• Rename is complete and consistent across all files, public re-exports, test fixtures, and NAPI bindings.
• Extracted map_envoy_stop_reason() is well-documented. The inline comments on each arm explain the WHY (reallocation vs. permanent destroy), which is genuinely non-obvious.
• The LifecycleCommand::stop_reason() fallthrough fix correctly enumerates Start and FireAlarm — if a future variant is added the compiler will catch the gap immediately.
• The try_on_activity() fix is good. The comment explaining why Loading | SleepFinalize | Destroying | Terminated silently drop activity signals is justified (non-obvious constraint) and well-written.
• Added ?task_stop_reason to the stop-actor log line — nice diagnostic addition.
• Test coverage: every test call site is updated, no tests were deleted.

Minor suggestions:

1. map_envoy_stop_reason parameter type — protocol::StopActorReason is probably Copy. Taking &reason is fine but slightly inconsistent with how the rest of the codebase passes enum values directly. Consider reason: protocol::StopActorReason (by value) to match the pattern used in shutdown_reason_label(reason: ShutdownKind).

2. ShutdownKind::ALL constant — metrics.rs uses a hardcoded array [ShutdownKind::Sleep, ShutdownKind::Destroy] to pre-register Prometheus labels. StateMutationReason has an ALL const for this purpose. Not a blocker, but worth adding to ShutdownKind for consistency so the metrics init and the enum stay in sync automatically.

3. PR description — The checklist is unfilled and the description is the default template. Since this does include a real behavioral fix (GoingAway/Lost semantics), a one-line summary of that change in the description would help reviewers and the git history.

Verdict

Approve with the minor notes above. The rename improves readability, the fallthrough elimination is the right call per the new CLAUDE.md rule, and the GoingAway/Lost fix is a genuine correctness improvement that was only visible because of the explicit enum matching.

Preview packages published to npm

Install with:

npm install rivetkit@pr-4765

All packages published as 0.0.0-pr.4765.eff8bc0 with tag pr-4765.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-eff8bc0
docker pull rivetdev/engine:full-eff8bc0

npm install rivetkit@pr-4765
npm install @rivetkit/react@pr-4765
npm install @rivetkit/rivetkit-napi@pr-4765
npm install @rivetkit/workflow-engine@pr-4765